SetDepth

SetDepth
Header:	Palettes.h		Carbon status:	Supported

Changes the pixel depth of a video device.

OSErr SetDepth (
    GDHandle gd, 
    SInt16 depth, 
    SInt16 whichFlags, 
    SInt16 flags
);

Parameter descriptions

gd: A handle to the GDevice structure of the video device whose pixel depth you wish to change.
depth: The mode ID returned by the HasDepth function indicating that the video device supports the desired pixel depth. Alternatively, you can pass the desired pixel depth directly in this parameter, although you should use the HasDepth function to ensure that the device supports this depth.
whichFlags: The gdDevType constant, which represents a bit in the gdFlags field of the GDevice structure. (If this bit is set to 0 in the GDevice structure, the video device is black and white; if the bit is set to 1, the device supports color.)
flags: The value 0 or 1. If you pass 0 in this parameter, the SetDepth function changes the video device to black and white; if you pass 1 in this parameter, SetDepth changes the video device to color.

function result: A result code. Returns zero if successful, or it returns a nonzero value if it cannot impose the desired depth and display mode on the requested device.

DISCUSSION

The SetDepth function does not change the 'scrn' resource; when the system is restarted, the original depth for this device is restored.

The Monitors control panel is the user interface for changing the pixel depth, color capabilities, and positions of video devices. Since the user can control the capabilities of the video device, your application should be flexible: although it may have a preferred pixel depth, your application should do its best to accommodate less than ideal conditions.

Use SetDepth only if your application can run on devices of a particular pixel depth and is unable to adapt to any other depth. Your application should display a dialog box that offers the user a choice between changing to that depth or canceling display of the image before your application uses SetDepth. Such a dialog box saves the user the trouble of going to the Monitors control panel before returning to your application.

SPECIAL CONSIDERATIONS

The SetDepth function may move or purge blocks of memory in the application heap; do not call this function at interrupt time.

AVAILABILITY

Supported in Carbon. Available in Carbon 1.0.2 and later when running Mac OS 8.1 or later.